home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 26
/
Cream of the Crop 26.iso
/
program
/
wil4c10.zip
/
WIL4C_U.TXT
< prev
Wrap
Text File
|
1997-07-26
|
84KB
|
2,523 lines
Winsock Interface Library
for C/C++
(WIL4C)
USERS MANUAL
Version 1.0
July 28, 1997
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 1997
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Voice : 205-881-4630
FAX : 205|880|0925
BBS : 205-880-9748
email : info@marshallsoft.com
web : www.marshallsoft.com
_______
____|__ | (R)
--+ | +-------------------
| ____|__ | Association of
| | |_| Shareware
|__| o | Professionals
--+--+ | +---------------------
|___|___| MEMBER
WIL4C Users Manual Page 1
C O N T E N T S
Chapter Page
1.0 Introduction................................................3
1.1 User Support............................................4
1.2 ASP Ombudsman...........................................4
1.3 Installation............................................5
1.4 Consulting Services.....................................5
2.0 Library Organization........................................6
2.1 Dynamic Link Libraries..................................6
2.2 Using the Library.......................................6
2.3 Compiling Programs......................................6
2.4 Using a MAKEFILE........................................6
2.5 Using an IDE............................................7
2.6 Compiling WIL4C.........................................9
2.7 Compiling Example Programs..............................9
3.0 Internet Programming.......................................10
3.1 Internet RFCs..........................................10
3.2 Protocol Layers........................................11
3.3 The Internet Protocol (IP).............................11
3.4 Socket Concepts........................................12
3.5 Client and Server Programming..........................14
3.6 Stream (TCP) Programming...............................14
3.7 Windows Winsock Programming............................14
3.8 Synchronous VS Asynchronous Programming................15
3.9 The ASYNC Functions....................................16
4.0 Internet Protocols.........................................20
4.1 Finger Protocol........................................20
4.2 SMTP Protocol..........................................21
4.3 POP3 Protocol..........................................23
4.4 NNTP Protocol..........................................25
4.5 FTP Protocol...........................................28
4.6 HTTP Protocol..........................................31
5.0 Problems...................................................33
6.0 Example Programs...........................................34
6.1 HOST...................................................34
6.2 SFINGR, AFINGER, and FINGER............................34
6.3 FROM...................................................34
6.4 MAIL...................................................35
6.5 FTP....................................................35
6.6 NEWS...................................................36
6.7 VIEW...................................................36
6.8 WHO_C and WHO_S........................................37
6.9 BCAST..................................................37
7.0 Legal Issues...............................................38
7.1 Registration...........................................38
7.2 License................................................39
7.3 Warranty...............................................39
8.0 Summary....................................................40
8.1 Revision History.......................................40
8.2 WIL Function Summary...................................40
9.0 Other MarshallSoft Computing Products......................42
WIL4C Users Manual Page 2
1.0 Introduction
The Winsock Interface Library for C/C++ (WIL4C) is a function library
that simplifies Winsock programming and provides support for the most
common Internet protocols such as DNS (Domain Name System), Finger,
SMTP (Simple Mail Transport Protocol), POP3 (Post Office Protocol
Version 3), FTP (File Transfer Protocol), NNTP (Network News
Transport Protocol), and HTTP (Hypertext Transfer Protocol).
Winsock network programming is not easy. Because of this, the primary
purpose in designing WIL was to simplify Winsock programming.
Winsock simplification is accomplished by:
(1) Handling details like converting from host byte order to network
byte order (and vice versa) as necessary automatically.
(2) Handling the creation and manipulation of winsock data
structures automatically.
(3) Proving a straight forward interface, using only necessary
arguments.
(4) Providing more powerful functions, which may perform multiple
Winsock functions.
The WIL can be called from any program capable of calling Windows API
functions, such as Delphi and Visual Basic.
Support for the most common Internet protocols is provided by the
ASYNC.C functions, which can transmit commands and receive responses
formatted as used by these protocols.
Lastly, a good selection of example programs are provided, covering
the major Internet protocols. The example programs are designed to
demonstrate how to use the WIL library functions. One of the best
ways to learn Winsock programming is to study these examples.
The shareware and registered versions are identical except for two
differences: (1) the shareware version displays the "shareware"
screen, and (2) the shareware version will "time out" after 20
minutes, limiting execution to a maximum of twenty minutes EACH time
a program is run. Of course, the registered version does not display
the shareware screen nor time out after twenty minutes.
We apologize for the inconvenience of the twenty minute timeout.
Please contact us if more time is needed in order to evaluate WIL4C.
WIL4C Users Manual Page 3
1.1 User Support
We want you to be successful in developing your applications using
WIL4C! We depend upon our customers to let us know what they need in
a winsock communications library. This means we are committed to
providing the best library that we can. If you have any suggestions
or comments, please let us know.
If you are having a problem using WIL4C, call us at 205-881-4630
between 1:30 PM and 9:30 PM CST Monday through Friday. You can also
call at other times and leave a message, and call back later for a
reply.
However, we can only answer questions with respect to using the WIL4C
library or our example programs. We cannot help you program your
application. See section 1.4 "Consulting Services".
If you are on the Internet, email us at info@marshallsoft.com. You
can also get the latest versions of our products from our anonymous
ftp site:
FTP: ftp.marshallsoft.com PATH: marshallsoft
The MarshallSoft Computing, Inc. newsletter "Comm Talk" is published
quarterly. It discusses various communications problems and
solutions using WIL4C as well as related information.
The latest copy of our newsletter can be found on our anonymous ftp
site (directory /marshallsoft/other) as well as our web site.
Web site: www.marshallsoft.com
Our FTP site can also be accessed from our Web site.
1.2 ASP Ombudsman
MarshallSoft Computing, Inc. is a member of the Association of
Shareware Professionals (ASP). ASP wants to make sure that the
shareware principle works for you. If you are unable to resolve a
shareware-related problem with an ASP member by contacting the member
directly, ASP may be able to help. The ASP Ombudsman can help you
resolve a dispute or problem with an ASP member, but does not provide
technical support for members' products. Please write to the ASP
Ombudsman at 545 Grover Road, Muskegon, MI USA 49442-9427, Fax
616-788-2765, or send a CompuServe message via CompuServe Mail to ASP
Ombudsman 70007,3536.
WIL4C Users Manual Page 4
1.3 Installation
(1) Before installation of WIL4C, your Windows C/C++ compiler should
already be installed on your system and tested. In particular,
include command line tools when installing your compiler.
(2) Make a backup copy of your distribution disk. Put your original
distribution disk in a safe place.
(3) Exit Windows into DOS, or start a DOS window:
(4) Create your WIL project directory, copy the WIL archive, then
unzip the archive. For example:
MKDIR WIL
PKUNZIP WIL4C10.ZIP WIL
(5) Use the provided install batch file (INSTALL) to install the
library. The format is:
INSTALL <compiler>
where <compiler> must be "MS" for Microsoft, "BC" for Borland, or
"WC" for Watcom. INSTALL performs the following copy operations:
Microsoft:
COPY WIL32M.LIB WIL32.LIB
COPY WIL32M.DLL WIL32.DLL
Borland:
COPY WIL32B.LIB WIL32.LIB
COPY WIL32B.DLL WIL32.DLL
Watcom:
COPY WIL32W.LIB WIL32.LIB
COPY WIL32W.DLL WIL32.DLL
WIL16.DLL is common for all of the supported compilers.
1.4 Consulting Services
We offer consulting services at $75 per hour, billed to your credit
card in 10 minute increments. A work authorization letter must be
signed and mailed or FAXed to us before we can start.
Questions dealing with the use of our library or our example programs
are covered as "support", for which there is no charge. Any other
questions are considered consulting.
WIL4C Users Manual Page 5
2.0 Library Overview
2.1 Dynamic Link Libraries
WIL4C includes both Win16 [WIL16] and a Win32 [WIL32] dynamic link
library (DLL). A DLL is characterized by the fact that it need not be
loaded until required by an application program and that only one
copy of the DLL is necessary regardless of the number of application
programs that use it. Contrast this to the traditional static library
which is bound to each and every application that uses it at link
time.
Since WIL4C is a DLL, only one copy of the WIL4C code and data is
loaded into memory regardless of the number of applications programs
that use it. For example, more than one instance of the test program
FINGER can be started. All copies of FINGER can run concurrently.
2.2 Using the Library
The WIL4C has been tested on a Gateway 2000 (25 MHz 80386-DX, Windows
3.1), a Gateway 2000 (66 MHz 80486-DX2, Windows 3.1), a Mid-West
Micro (150 MHz Pentium, Windows 95), and a Toshiba Satellite (100 MHz
Pentium, Windows 95).
WIL4C has also been tested with Microsoft Visual C/C++, Borland C/C++
(including C Builder), Turbo C/C++, and Watcom C/C++.
2.3 Compiling Programs
The example programs can be compiled by using either the provided
makefiles or creating a project file for the IDE. Separate makefiles
are provide for Win16 and Win32. 16-bit makefile end with "16" while
32-bit makefiles end with "32".
2.4 Using a MAKEFILE
Makefiles originated on UNIX systems. They are the standard way that
C/C++ programs are constructed in command line environments. Windows
programs can be constructed with makefiles running DOS using command
line Windows compilers.
Makefiles are provided for Microsoft, Borland, and WATCOM command
line compilers. Makefiles have file extensions of "_M_" for
Microsoft, "_B_" for Borland, and "_W_" for WATCOM. Thus,
FINGER16._W_ is the Watcom Win16 makefile for FINGER and FINGER32._M_
is the Microsoft Win32 makefile.
Turbo C/C++ for Windows and Borland C Builder do not support command
line makefiles.
Refer to MAKEFILE.TXT for more information on makefiles.
WIL4C Users Manual Page 6
2.5 Using an IDE
All current windows compilers have an Integrated Development
Environment (IDE) for building application programs in the Windows
environment. Since there is no standard format for IDE project files,
file names must be entered into the IDE from the keyboard. Each
example program has a project text file (e.g. FINGER.PRJ) which
contains the list of filenames that must be entered into the IDE.
We do not distribute IDE files in our package because (1) they are
very large, (2) they are not always upwardly compatible with previous
versions of a particular IDE, (3) there is no standard project file
format between compiler manufactures, and (4) they often must be
modified to provide the correct path names.
However, creating a project file within the IDE is very easy. Each
application has a project file . Each project file contains the
filenames that must be entered into the IDE.
For each IDE, you will have to enter these filenames into the IDE.
This is usually done with the INS key except for the Microsoft
Developer, which uses menu commands. Be careful to enter all
filenames as listed in the ".PRJ" file.
All of the example application programs have been built using IDEs
from Microsoft, Borland, and Watcom. However, there are differences
between IDE versions from the same compiler manufacturer.
All of the IDEs use the concept of a file hierarchy. For example, the
Finger file hierarchy in the IDE (for 32-bit) should look like:
FINGER.EXE
|-- ABOUT.C
|-- ASYNC.C
|-- FINGER.C
|-- FINGER.DEF
|-- FINGER.RC
|-- PAINT.C
|-- STR.C
|-- WIL32.LIB
Replace WIL32.LIB above with WIL16.LIB for 16-bit applications. The
order of the files is not significant.
2.5.1 Microsoft IDE
Choose "Project", then "New". Select Win16 [Win32] as the target. A
dialog box will then pop up into which the project file names are
entered.
WIL4C Users Manual Page 7
2.5.2 Microsoft Developer
Choose "File", then "New", then "Project Workspace". Select
"Application" for "Type:" and your project name for "Name:". Choose
Win16 or Win32 for platform. Then select "Create".
Select "Insert", then "Files into Project". Add all filenames as
listed in the ".PRJ" file corresponding to the project you are
building. Lastly, select "Rebuild All".
2.5.3 Borland IDE
Turn off LINKER case sensitivities: Choose "Options", "Projects",
"Linker", "General". Turn off the "case sensitive link" and "case
sensitive exports and imports" boxes.
Next, choose "Project", then "New Project". Use the INS (Insert) key
to pop up a dialog box into which the project file names are entered.
Select "GUI" for the "Target Model:" Only "Runtime" and "Dynamic"
should be checked for "Standard Libraries:"
NOTE1: If, after linking in the IDE, you get unresolved external
references to the communications library functions in which each
function name is all upper case, then you have NOT turned off case
sensitivity as described above.
NOTE2: If you get errors compiling the windows header file
"WINDOWS.H", turn on "Borland Extensions" in "Options", "Project",
"Compiler", "Source".
2.5.4 Turbo C IDE
Follow the same directions as above, except that the "Target Model:"
can be any listed.
2.5.5 Borland C Builder
Choose "File" / "Open Project" on the menu bar. Load BCB_PRJ.MAK.
Then, choose "Build All" from "Project" to create the executable.
2.5.6 Watcom IDE
Choose "File", then "New Project". Enter the project name and then
choose Win16 [Win32] as the target. Use the INS (Insert) key to pop
up a dialog box into which the project file names are entered.
Select "Options" from the main window, then "C Compiler Switches",
then "10". Memory Models and Processor Switches". Check "80386 Stack
based calling [-3s]", then check "32-bit Flat model [-mf]".
WIL4C Users Manual Page 8
2.6 Compiling WIL4C
Precompiled DLL's are provided on disk for all the supported
compilers. Registered users can recompile WIL.C in order to create
WIL16.DLL and WIL32.DLL. Makefiles are provided for each compiler.
For Microsoft C, type:
NMAKE -f WIL16._M_
NMAKE -f WIL32._M_
For Borland C, type:
MAKE -f WIL16._B_
MAKE -f WIL32._B_
For Watcom C, type:
WMAKE -f WIL16._W_
WMAKE -f WIL32._W_
2.7 Compiling Example Programs
There are makefiles provided for each of the example programs.
For example, to compile FINGER:
For Microsoft C, type:
NMAKE -f FINGER16._M_
NMAKE -f FINGER32._M_
For Borland C, type:
MAKE -f FINGER16._B_
MAKE -f FINGER32._B_
For Watcom C, type:
WMAKE -f FINGER16._W_
WMAKE -f FINGER32._W_
WIL.C can also be recompiled within the IDE.
WIL4C Users Manual Page 9
3.0 Internet Network Programming
It is assumed that the user of the WIL library is familiar with the
Internet and programming, but not necessarily network programming.
For more detailed information on the structure of the Internet, refer
to one of the many excellent books on the subject. One of the best is
Internetworking with TCP/IP, Volume I by Douglas E. Comer (Prentice
Hall, ISBN 0-13-216987-8).
One of the best ways to learn network programming is to study (and
eventually modify) example code. For this reason, a good selection of
program examples are provided.
3.1 Internet RFCs
The various Internet standards are defined in "Requests for
Comments", or RFCs. RFCs are text files, and are available on the
Internet at ftp://ds.internic.net. The index of all RFC documents is
found in file rfc-index.txt.
Some important RFCs include:
RFC 791 : The Internet Protocol (IP)
RFC 821 : Simple Mail Transport Protocol (SMTP).
RFC 822 : SMTP Message Format.
RFC 959 : File Transfer Protocol (FTP).
RFC 1036 : Network News Transport Protocol (NNTP).
RFC 1288 : The Finger protocol.
RFC 1460 : Post Office Protocol, Version 3 (POP3).
RFC 1521 : Multipurpose Extensions Mail Extensions (MIME).
RFC 2068 : Hypertext Transfer Protocol 1.1 (HTTP).
The above is just a sampling of the thousands of RFCs. Anyone wanting
to implement a particular protocol should download a copy of the
appropriate RFCs from the Internic.
In addition to RFCs, the Internic also publishes additional classes
of documents:
(1) Internet Drafts (ID).
(2) For Your Information (FYI).
(3) Standard RFCs (STD).
These documents are also found at ftp://ds.internic.net.
WIL4C Users Manual Page 10
3.2 Protocol Layers
The internet protocol layers look like:
+---------------------+
| Application Program | FINGER.C, MAIL.C, FTP.C, ...
+-+-----+-------------+
| |
| +-+-----------+
| | WIL Library | WIL16.DLL and WIL32.DLL
| +-+-----------+
| |
+-+-----+-----+
| WINSOCK DLL | WINSOCK.DLL and WSOCK32.DLL
+-------+-----+
|
+---------+
| |
+-------+--+ +---+------+
| TCP code | | UDP code | (vendor specific)
+--------+-+ ++---------+
| |
+-+-----+-+
| IP code |
+----+----+
|
+-------+--------+
| Network Driver |
+-------+--------+
|
+-------+--------+
| LAN or PPP |
+----------------+
Each of the example programs uses the WIL (Winsock Interface Library)
to simplify access to the WINSOCK.
3.3 The Internet Protocol (IP)
The Internet Protocol (IP) is the basis upon everthing else is built.
It is documented in RFC 791.
3.3.1 Best Effort Delivery
Internet Protocol (IP) provides a "best effort" in delivering IP
packets. Packets may arrive out of order, or may not arrive at all.
The TCP (Transport Control Protocol) and UDP (User Datagram Protocol)
are built on top of IP and perform additional error detection and
correction.
WIL4C Users Manual Page 11
3.3.2 IP Addresses
Each host computer is assigned an unique 32-bit internet address that
is used for all internet communications. Thus, if you dial up your
Internet Service Provider (ISP), you are assigned an IP address owned
by the ISP which is used to uniquely identify you while you are
connected.
The IP address is often written as four 8-bit decimal octets (bytes)
separated by decimal points. For example, the 32-bit hexidecimal
number 12AF7B02 can be written as
18.175.123.2
The internet standard for byte ordering within an integer is "Big
Endian" (most significant byte first) and is denoted as the "network
byte order". The host byte order depends on the particular computer
architecture. For Intel based PCs, the host byte ordering is "Little
Endian" (least significant byte first).
The WINSOCK provides functions to convert between them. The Winsock
Inteface Library (WIL) library always deals with addresses in host
order, converting as necessary when communicating with the WINSOCK.
3.4 Socket Concepts
A socket is a small integer number used to identify the endpoint for
TCP/IP communications. It is the fundamental Internet network
programming interface.
3.4.1 Socket Ports
Internet communications occurs between two end-points each of which
is defined by an IP address and a "port number", a 16-bit integer
number. In this way, multiple sessions between the same two computers
can occur simultaneously, each using a different port number.
Established Internet Protocols have a port number called the "well
known port" assigned to them. For example, FTP always uses port
number 21.
Application server programs should use a port number of at least
5000. See the WHO_S program for an example server.
Sockets are further differentiated as to whether they are TCP sockets
or UDP sockets. WIL supports TCP sockets only.
WIL4C Users Manual Page 12
3.4.2 Socket Address Structure
The socket requires a socket address structure which contains
additional information neccessary (port number, remote IP address,
etc.) for communications to a remote endpoint.
The WIL library handles all details of socket address structures.
3.4.3 TCP and UDP Sockets
There are two types of sockets: datagrams (UDP sockets) and streams
(TCP sockets).
UDP sockets are rarely used in network application programming, and
are thus not implemented in WIL.
TCP sockets implement bi-directional data streams, guaranteed to be
error free. TCP is used for most application level net programming,
including all of the example programs.
3.5 Client and Server Side
There are two distinct classes of internet programming: Client side
and Server side.
3.5.1 Server Programs
A server is a program that provides some service. It runs
continuously, waiting for a client to connect to it. Server programs
listen for incoming connections. When an incoming connection is
detected, the server program can accept the connection, after which
the socket I/O can occur.
+------+
| BIND |
+--+---+
|
+---+----+ +--------+
| LISTEN +------------+ ACCEPT |
+--------+ +--------+
The program WHO_S is an example of a simple server program. It
provides a simple "whois" service for its client WHO_C. Also see
WHO_C, which is an example of a client for the WHO_S server.
WIL4C Users Manual Page 13
3.5.2 Client Programs
Most user application progams are "client side" programs. A client
program is a program that connects to a server program to perform
some service. A client program is run only when the service is
needed.
FINGER, VIEW, MAIL, FROM, FTP, NEWS, and WHO_C are all examples of
client programs.
3.6 Stream (TCP) Programming
TCP (Transmission Control Protocol) is the basic protocol upon which
all of the example programs are written. Some important
characteristics of a TCP connection are:
(1) The TCP connection as a bi-direction pipe, or stream. There is no
concept of packets at the TCP level. What goes in one end comes out
the other.
(2) TCP provides for a reliable connection. Addition checksums are
not required.
(3) TCP uses a 16-bit port number to identify the connection
endpoint. Thus, an "endpoint" is the pair (host, port). This allows a
given host to be running multiple concurrent sessions, each with a
unique endpoint.
3.7 Windows Winsock Sockets
There are really two classes of Winsock API calls: blocking and
non-blocking (asynchronous). Sockets were originally designed for the
UNIX operating system, and block until a requested operation
completes. This works well in a true multi-tasked operating system
like UNIX.
When the Windows Winsock API was designed for Windows 3.X, several
additional asynchronous winsock commands were added in addition to
the traditional blocking commands.
3.8 Synchronous Versus Asynchronous Programming
There are two different styles of Winsock programming: Synchonous and
Asychronous. Each has its advantages and disadvantages. WIL4C
supports both styles of programming.
Examples of the synchronous style include HOST, SFINGR, VIEW, WHO_S,
and WHO_C.
Example of the asynchronous style include AFINGR, FINGER, NNTP, MAIL,
and FROM.
FTP is an example employing both synchronous and asynchronous styles.
WIL4C Users Manual Page 14
3.8.1 Synchronous Programming
The synchronous style of Winsock programming is characterized by
sending a command, then waiting for the response in a polling loop.
Typically, the hour glass cursor is displayed during this waiting
period. This style is typical of UNIX programs, but does not mesh
well with the Windows message event loop, except for perhaps program
threads running under Win32. On the positive side, synchronous
programs are easier to follow and require less code.
3.8.2 Asynchronous Programming
The asynchronous style of Winsock programming is characterized by
sending a command, then continuing on with other work until a message
arrives signifying the completion of the command request. This style
of Winsock programming uses the Windows message loop mechanism, and
is considered the "Windows friendly" approach.
Compare the three Finger programs SFINGR, AFINGR, and FINGER. SFINGR
uses the synchronous style, AFINGR uses the asynchronous style, and
FINGER uses the asynchronous style as implemented with the ASYNC.C
module functions.
Studying the three Finger programs (SFINGR, SFINGR, and FINGER) is a
good way to compare the synchronous versus the two asynchronous
styles of Winsock programming.
Refer to the following section "The ASYNC Functions" for details on
how the ASYNC functions operate. In particular, compare AFINGR (which
does not use the ASYNC functions) to FINGER (which does).
WIL4C Users Manual Page 15
3.9 The ASYNC Functions
The ASYNC functions operate using the wilAwaitEvent function to post
winsock event messages to WM_USER, which are passed to the ASYNC code
for processing. Messages may also be posted to WM_USER+1 to notify
the application of the completion of a sequence of requested events.
In practice, this is simpler than it sounds. Examine FINGER.C to see
an example.
The ASYNC functions are contained in the file ASYNC.C.
3.9.1 AsyncConnect
The purpose of the AsyncConnect function is to connect to a remote
host.
SOCKET AsyncConnect(
HWND hWnd, /* window to post messages */
LPSTR ServerType, /* server type (eg: POP3) */
LPSTR ServerName, /* server name (eg: mail.iquest.com) */
int Port, /* sever port */
int SuccessMsg, /* wParam for WM_MSG if successful */
int FailureMsg) /* wParam for WM_MSG if failure */
In the following call to AsyncConnect, the caller is requesting a
connection to a POP3 server with name "mail.iquest.com", using the
well known POP3 port 110. If the connection is successful, message
SUCCESS_MSG should be posted for event WM_USER+1 in window hWnd.
If unsuccessful, FAILURE_MSG should be posted for event WM_USER+1.
Socket = AsyncConnect(hMainWnd, "POP3", "mail.iquest.com",
110, SUCCESS_MSG, FAILURE_MSG);
Upon success, the returned socket may be used for socket I/O.
WIL4C Users Manual Page 16
3.9.2 AsyncRead
The purpose of the AsyncRead function is to wait for any incoming
data on the port specified in the call to AsyncConnect.
int AsyncRead(
int SuccessMsg, /* wParam for WM_MSG if successful */
int FailureMsg, /* wParam for WM_MSG if failure */
int ReadType) /* async read type */
The ReadType can be any of the following:
ReadType Symbol Response Expected
ASYNC_NONE No server response is expected.
ASYNC_SINGLE_LINE Single Line of Text (LOT).
ASYNC_MULTIPLE_LINES Multiple LOTs.
ASYNC_SINGLE_CODED Single line: decimal response plus LOT.
ASYNC_MULTIPLE_CODED Multiple lines: decimal response plus LOT.
ASYNC_PLUS_MINUS Single line: "+OK" or "-ERR" plus LOT.
The "Line of Text" (LOT) above consists of 7-bit ASCII characters
followed by a carriage return (CR) and line feed (LF). The "decimal
response" code consists of 3 decimal ASCII digits (eg: "125").
In the following call to AsyncRead, the caller is awaiting a single
line of test. Once the incoming text line is read and optionally
echoed to the display (see AsyncSetEcho), message SUCCESS_MSG
should be posted for event WM_USER+1. If unsuccessful, FAILURE_MSG
should be posted for event WM_USER+1.
AsyncRead = AsyncRead(SUCCESS_MSG, FAILURE_MSG, ASYNC_SINGLE_LINE);
3.9.3 AsyncWrite
The purpose of the AsyncWrite command is to write the specified
command on the port specified in the call to AsyncConnect.
int AsyncWrite(
LPSTR Command, /* command to send to server */
int SuccessMsg, /* wParam for WM_MSG if successful */
int FailureMsg) /* wParam for WM_MSG if failure */
In the following call to AsyncWrite, the caller wants to write the
text line in 'Command'. Once the text line is written and optionally
echoed to the display (see AsyncSetEcho), message SUCCESS_MSG should
be posted for event WM_USER+1. If unsuccessful, FAILURE_MSG should be
posted for event WM_USER+1.
AsyncRead = AsyncWrite("LIST", SUCCESS_MSG, FAILURE_MSG);
WIL4C Users Manual Page 17
3.9.4 AsyncCommand
The purpose of the AsyncCommand command is to combine the functions of
AsyncWrite and AsyncRead into a single command.
See AsyncWrite and AsyncRead above. Also refer to ther example
programs which use AsyncCommand.
int AsyncCommand(
LPSTR Command, /* command to send to server */
int SuccessMsg, /* wParam for WM_MSG if successful */
int FailureMsg, /* wParam for WM_MSG if failure */
int ReadType) /* async read type */
3.9.5 AsyncGetBufPtr
The purpose of the AsyncGetBufPtr is to return a pointer to the text
line buffer used by AsyncRead, AsyncWrite, and AsyncCommand.
LPSTR AsyncGetBufPtr(void);
3.9.6 AsyncProcessMsg
The purpose of the AsyncProcessMsg command is to process WM_USER
messages. The main window (as specified by hWnd in the call to
AsyncConnect) should contain the following line in the main event
loop:
case WM_USER:
AsyncProcessMsg(wParam)
break;
The application should NOT post WM_USER messages when using the ASYNC
functions.
3.9.7 AsyncSetEcho
The purpose of the AsyncSetEcho function is to set the echo flag for
all subsequent ASYNC processing.
int AsyncSetEcho(int EchoFlag);
If the EchoFlag is TRUE, all text strings sent to (and received from)
the server are echoed to the display. The AsyncSetEcho function
returns the previous value of the echo flag.
WIL4C Users Manual Page 18
3.9.8 AsyncSetDebug
The purpose of the AsyncSetDebug function is to set the debug flag.
The DebugFlag is used by the ASYNC code to display additional
information. The AsyncSetDebug flag is meant for debugging ASYNC
calls.
int AsyncSetDebug(int DebugFlag);
The programmer should rarely have need to use this function.
3.9.9 POST Macros
Posting to WM_USER is reserved for ASYNC functions. Posting to
WM_USER+1 may be done by both ASYNC finctions and application
functions.
Two macros are defined for posting messages to WM_USER+1. The
POST_MSG macro posts message (m) with parameter value 0. The
POST_PARM macro posts message (m) with parameter (p).
The POST_PARM macro is used pass back the numeric 3-digit response
codes from SMTP, FTP, etc., or the "+OK" (100) or "-ERR" (500) POP3
codes.
The macros are defined in ASYNC.H as
#define POST_MSG(m) PostMessage(hMainWnd,WM_USER+1,(m),0)
#define POST_PARM(m,p) PostMessage(hMainWnd,WM_USER+1,(m),(p))
The POST macros are used by both the ASYNC functions and the example
code.
WIL4C Users Manual Page 19
4.0 Internet Protocols
The Internet protocols to follow all communicate using ASCII text
lines. Each line ends with a carriage return, line feed (CR, LF)
pair. The client program initiates the protocol by connecting to the
server. What happens next is dependent on the particular protocol.
The following discussions are for overview only. Refer to the proper
RFCs for details on the protocols.
4.1 Finger
The Finger protocol is one of the simplest Internet protocols. For
this reason, it is an excellent protocol to study for those without
any Winsock programming experience.
Finger allows one to retrieve information about a remote user on a
remote host machine. If the remote user has a "plan file", then this
information is returned in addition to the normal Finger data.
Finger uses TCP with well known port number 79.
The client side of the Finger protocol works as follows:
(1) The client connects to the Finger sever on the remote host using
TCP and port 79. The server does NOT send a greeting.
(2) Once connected, the client sends a single line of text containing
the login name of the user for which information is wanted.
(3) The Finger server will send a series of text lines back. After
the last line, the Finger server closes the connection.
The Finger protocol is a very simple protocol. Three example Finger
programs are included:
(1) SFINGR: Synchronous version of Finger.
(2) AFINGR: Asynchronous version of Finger.
(3) FINGER: Asynchronous version of Finger using the ASYNC functions.
Also see RFC 1288 for a detailed description of Finger.
Note that not all Internet hosts provide Finger servers, although
many do.
WIL4C Users Manual Page 20
4.2 SMTP
The SMTP (Simple Mail Transport Protocol) protocol allows the user to
send mail to a remote user. SMTP uses TCP with well known port number
25. All mail messages must consist of one or more lines of 7-bit
ASCII characters, each line terminating with a carriage return, line
feed pair.
All server responses begin with a 3 digit decimal response code.
Values of 500 and above indicate an error condition.
4.2.1 SMTP Protocol
The client side of the SMTP protocol works as follows:
(1) The client connects to the SMTP server on the remote host using
well known port 25. Once connected, the server responds with a
greeting message, which may be one or more lines.
(2) The client sends the "HELO myhost.com" command to the server
where myhost.com is the local host name. The server responds with a
greeting message.
(3) The client sends the "MAIL FROM" command as shown in the example
below. The server should respond with "250 OK".
(4) The client sends the "RCPT TO" command to identify the recipient
of the mail. The server responds with "250 OK". Additional recipients
are sent by the client as required by sending additional "RCPT TO"
commands.
(5) The client sends the "DATA" command as shown below. The server
responds with "250 OK".
(6) The client sends the mail message as a series of text lines, each
terminated by a carriage return, line feed pair. A text line
consisting of just a period is "quoted" by adding a second period,
since a line with a lone period indicates the end of the message.
After all message lines have been sent, a line with a lone period
(".\r\n") is sent to end the transmission. The server responds with
"250 OK".
(7) If another email is to be send, go back to step (4) above,
otherwise sign off by sending the "QUIT" command.
WIL4C Users Manual Page 21
4.2.2 SMTP Example
In the following example, the caller mike@marshallsoft.com sends a 3
line email message to Pierre at pierre@louve.com. Each line sent and
received terminates with a carriage return, line feed pair. The "C:"
(for client) and "S:" (for server) are not part of the protocol, but
are shown to identify the client (C:) and server (S:) originated
messages.
C: (Connects to remote SMTP server).
S: 220 LOUVE.COM SMTP server version 1.2.1
C: HELO marshallsoft.com
S: 250 Nice to meet you marshallsoft.com
C: MAIL FROM:<mike@marshallsoft.com>
S: 250 OK
C: RCPT TO:<pierre@louve.com>
S: 250 OK
C: DATA
S: 250 OK
C: first line of email
C: second line of email
C: third line of email
C: .
S: 250 OK
C: QUIT
S: 221 au revoir.
Refer to the MAIL and BCAST programs for examples of a SMTP client.
Also see RFC 821 for a complete description of SMTP.
WIL4C Users Manual Page 22
4.3 POP3
The POP3 (Post Office Protocol version 3) protocol allows the user to
retrieve mail from his POP3 server. POP3 uses TCP with well known port
number 110.
All server responses consists of a single line of text ending with a
carriage return, line feed pair and beginning with either a "+OK" or
"-ERR".
4.3.1 POP3 Protocol
The client side of the POP3 protocol works as follows:
(1) The client connects to the POP3 sever on the remote host using
TCP and port 110. The server responds with its greeting.
(2) The client sends the USER command to identify the account. The
server responds with "+OK".
(3) The client sends the password for the USER account using the PASS
command. The server responds with a "+OK".
(4) The client is now "logged onto" the POP3 server. Several commands
can now be sent including:
(a) The STAT command request the # of messages (and total bytes)
waiting.
(b) The RETR command retrieves a particular message number.
(c) The DELE command deletes a particular message number
Refer to the following example for the usage of these commands.
(5) After all processing is done, the QUIT command is sent to log off
of the POP3 server. The server responds with "+OK".
Note that you must have a POP3 account set up by the host computer's
system administrator. Mail sent to you is queued on your POP3 account
for retrieval by you.
WIL4C Users Manual Page 23
4.3.2 POP3 Example
In the following example, Pierre has a POP3 account set up with user
name "Pierre" and password "francaise". The client program connects
to the POP3 server, gets the message status, receives the first
message, and then deletes it.
C: (Connects to remote POP3 server).
S: +OK server SuperPOP ready.
C: USER Pierre
S: +OK user is Pierre
C: PASS francaise
S: +OK Pierre's maildrop has 2 messages.
C: STAT
S: +OK 2 1950
C: RETR 1
S: +OK 1050 bytes
S: (1st line of email message 1)
S: (2nd line of email message 1)
:
S: (last line of email message 1)
S: .
C: DELE 1
S: +OK message 1 deleted
C: QUIT
S: +OK goodbye.
Refer to the FROM and MAIL programs for examples of a POP3 client.
Also see RFC 1460 for a complete description of SMTP.
WIL4C Users Manual Page 24
4.4 NNTP
The NNTP (Network News Transport Protocol) protocol allows the
client to download (and upload) network news articles from his NNTP
server. NNTP uses TCP with well known port number 119.
The client sends text command lines to the server, and the server
responds with a 3 digit numeric coded response line plus the
requested text information. If text information is sent by the
server, the last line will consist of (a text line with) a single
period. Server response codes of 500 and above indicate an error
condition.
The NTTP news server maintains a list of news articles grouped into
sets called "newsgroups", each of which has a name. The LIST command
can be used to read all newsgroups. A particular newgroup must be
selected by the GROUP command before any news articles can be read.
Each newsgroup consists of zero or more articles. Individual articles
are numbered and are deleted by the server after some period of time
after first receiving the article, depending on the individual
server. The article number of deleted articles are not reused.
Each article consists of two parts: the article header and the
article body. The article header consists of a short summary of the
article body itself. The server maintains a "current pointer" to the
current article, initialized to the first article in the newsgroup.
Once a newsgroup has been selected, news headers and/or articles can
be read. Commands include:
HEAD : read the current article header.
HEAD ddd : read article header number ddd (eg: READ 1286).
ARTICLE : read the current article.
ARTICLE ddd : read article number ddd.
NEXT : advance to next article in the newsgroup.
LAST : advance to last article in the newsgroup.
Articles can also be posted by the NTTP client by using the POST
command, if allowed for the particular newsgroup.
WIL4C Users Manual Page 25
4.4.1 NNTP Protocol
The client side of the NNTP protocol works as follows:
(1) The client connects to the NNTP sever on the host (typically your
ISP) using TCP and port 119. The server responds with its greeting
message.
(2) The client may send a LIST command to request a list of
newsgroups. The server responds with a (usually very long) list of
newsgroups.
(3) The client selects a newsgroup using the GROUP command. The
server responds with a response line consisting of the response code,
the number of articles, the first article number, the last article
number, and the group selected. For example
211 1982 18726 21918 comp.lang.c
(4) The client requests article headers by using the HEADER command
and the article body itself by using the ARTICLE command. The client
may also advance the current article pointer by using the NEXT or
LAST command. Note that the NEXT and LAST command do not retrieve a
article header or the article body itself, but rather just move the
current article pointer so that subsequent HEADER or ARTICLE commands
(without a specified article number argument) will retrieve the
current article header or article body.
(5) The client can post articles, if allowed, by using the POST
command. After sending the POST command (without any arguments), the
server will prompt you to send the body of the article to be posted,
which consists of multiple text lines, followed by a line with just a
period.
Refer to RFC 1036 for details on article formats.
WIL4C Users Manual Page 26
4.4.2 NNTP Example
In the following NNTP session, the client connects to the NTTP
server, request a list of all newsgroups, selects newsgroup
comp.lang.c, request the current (first) article, request the last
article, then quits.
C: (Connects to NTTP server using TCP on port 119).
S: SuperNTTP ready. Posting OK.
C: LIST
S: comp.protocols.tcp-ip 514 819 Y
S: comp.lang.c 1182 1271
:
S: .
C: GROUP comp.lang.c
S: 211 1982 18726 21918 comp.lang.c
C: ARTICLE
S: 1st line of current article (#18726)
S: 2nd line of current article (#18726)
:
S: last line of current article (#18726)
S: .
C: LAST
S: Article 21918 selected. Use ARTICLE to retrieve article.
C: ARTICLE
S: 1st line of current article (#21918)
S: 2nd line of current article (#21918)
:
S: last line of current article (#21918)
S: .
C: QUIT
Refer to the NEWS program for an example of a NNTP client. Note that
the example program NEWS does not support article posting.
Refer to RFC 1036 for a complete description of NNTP.
WIL4C Users Manual Page 27
4.5 FTP
The FTP (File Transfer Protocol) protocol allows the user to upload
and download text and binary files. FTP uses TCP with well known port
number 21.
Two types of FTP service exists. The first is where the client
connects to a remote host for which he knows the password, allowing
him both read and write access.
The second type of FTP service is called "anonymous FTP" in which the
USER name is "anonymous" ("ftp" is sometimers acceptable instead of
"anonymous") with the password set to the clients' email address.
This type of FTP service is very common on the Internet. Examples
include the MarshallSoft Computing anonymous FTP site at
"ftp.marshallsoft.com".
The FTP server responds to client commands with a 3 digit number
response code followed by the text of the repsonse message, and
ending with a carriage return, line feed pair. Response codes of 500
and above indicate a fatal error condition, 400 to 499 indicate a
recoverable error condition (try the command again), while codes of
100 through 399 indicate that all went OK. Refer to RFC 959 for more
details on FTP response codes.
The FTP server may respond with a multi-line response. A dash after
the response code indicates that this is not the last response line.
100-1st line of response.
100-2nd line of response.
100 last line of response.
Occassionally, other response codes are sent before the last response
line, which must always have the same response code as the first
response line. For example,
100-1st line of response for code 100.
101 1st line ine of response for code 101.
100 last line of response.
FTP does not use the port on which it connects (the control port) to
transfer data. Rather, the FTP specifies (using the control port)
which port to establish a data connection on using the PORT command
(see below). The FTP client then listens on this port for a
connection, after which data can be transferred. After all data is
transferred, the data port is closed.
WIL4C Users Manual Page 28
4.5.1 FTP Protocol
The FTP protocol works as follows:
(1) The client connects to the FTP sever on the remote host using TCP
and port 21. The server responds with its greeting.
(2) The client sends the USER command to identify the account. The
server responds with response code 331.
(3) The client sends the password for the USER account using the PASS
command. The server responds with response code 230.
(4) The client is now "logged onto" the FTP server. Several commands
can now be sent including:
(a) The CWD command changes the working directory on the remote
machine. If you connect to ftp.marshallsoft.com, you should
use the CWD command to change the working directory to
"marshallsoft".
(b) The LIST command lists all the files in the directory on the
remote computer. The LIST command does a formatted list, while
the NLST command just lists the filenames. The LIST (and NLST)
command requires that the PORT command (see below) be issued
first to establish the data port.
(c) The TYPE command is used to set either ASCII (TYPE A) or binary
mode (TYPE I) to be used for subsequent file transfers. The
default is ASCII. The ASCII and BINARY menu commands in the
example program FTP.C issue the FTP TYPE command.
The TYPE command should be used to set binary mode (see the
example program FTP.C) before transfering binary files.
(f) The PORT command is used to specify the port over which data
will be transferred. The PORT command must be used before using
the LIST, NLST, RETR or STOR command. For example, to specify
data port 6146 (256*24 + 2) using our (not the remote
machines) IP address of 165.113.131.70, we use
PORT 165,113,131,70,24,2
(e) The RETR command is used to download a file from the remote
computer, using the type as set by the TYPE command, and the
data port specified by the PORT command. The data port is
closed immediately after all data is tranferred.
(f) The STOR command is used to upload a file to the remote
computer, using the type as set by the TYPE command, and the
data port specified by the PORT command. The data port is
closed immediately after all data is tranferred.
Note that most anonymous FTP sites do not allow uploading.
(g) The QUIT command logs off of the FTP server.
WIL4C Users Manual Page 29
4.5.2 FTP Example
In the following FTP session, Pierre connects to a FTP server as
anonymous, lists all files, changes current directory to
"marshallsoft/other", sets binary file type, downloads file
DISKBK11.ZIP, then logs off.
C: (Connects to remote FTP server).
S: 220 SuperFTP server is ready.
C: USER anonymous
S: 331 Use email address for password.
C: PASS pierre@louve.com
S: 230-User Pierre logged on.
S: 230 This site allows read access only!
C: LIST
S: (1st line of directory listing)
S: (2nd line of directory listing)
:
S: (last line of directory listing)
S: .
C: CWD marshallsoft/other
S: 250 CWD command successful.
C: TYPE I
S: 200 Type is set to I.
C: PORT 11,231,11,14,20,15
S: 200 Port command successful.
C: GET diskbk11.zip
S: 150 Opening BINARY mode data connection for diskbk11.zip
(file comes in on data port, after which is is closed).
S: 226 Transfer complete.
C: QUIT
S: Au revoir Pierre!
Refer to the FTP program for an example of a FTP client.
Refer to RFC 959 for a complete description of FTP.
WIL4C Users Manual Page 30
4.6 HTTP
The HTTP (Hyper Text Transfer Protocol) protocol defines the
interation between World-Wide-Web (WWW) servers and WWW clients,
popularly known as "Web Browsers".
HTTP uses TCP with well known port number 80, and is documented in
RFC 2068.
HTTP is a complicated protocol. RFC 2068 describing HTTP/1.1 is 162
pages in length. If you want to develop a web browser, you must get a
copy of RFC 2068 from the Internic.
You will also need to have a knowledge of HTML (Hypertext Markup
Language) in order to interprete the data sent by the HTTP server.
Fortunately, there are several very good books on HTML such as "Teach
Yourself Web Publishing with HTML in 14 Days" by Laura LeMay (Sams
Net).
A very good way to get comfortable with HTML is to build your own WEB
site. Most ISPs (Intenet Service Providers) make provisions for their
customers to build "personal" web sites.
With some practical experience "surfing the web", a knowledge of
HTML, RFC2068, and the example program VIEW.C, you are ready to write
a HTTP application.
4.6.1 HTTP Protocol
HTTP commands are termed "Methods". These commands are case-sensitive
and include only two required (for all HTTP servers) commands: GET
and HEAD.
The GET command is the fundamental command which retrieves HTML
pages. For example,
GET /index.html HTTP/1.0
requests page INDEX.HTML.
The HEAD method is identical to GET except that only "meta"
information is returned for the page.
The HTTP client connects to the HTTP server on the remote host, sends
a command, receives a response, then terminates the connection. This
is repeated for each HTTP command.
The server response consists of header text, followed by a blank
line, followed by the actual HTML page requested. The first line of
the header text consists of the status return, such as:
HTTP/1.0 200 OK
Return value of 500 & above are server errors, and 400 to 499 are
client errors.
WIL4C Users Manual Page 31
4.6.2 HTTP Example
Suppose that the following Web page HELLO.HTM is on the MarshallSoft
Web site (www.marshallsoft.com).
<HTML> <HEAD>
<TITLE> MarshallSoft Computing, Inc. </TITLE>
</HEAD>
<H1> Hello </H1>
Hello, world!
</BODY> </HTML>
The following exchange with the HTTP server on the host requests the
page HELLO.HTM.
C: (Connects to remote FTP server).
C: GET /index.html HTTP/1.0
S: HTTP/1.0 200 OK
S: Date: Wed, 09 Jul 1997 20:43:59 GMT
S: Server: Apache/1.1.3
S: Content-type: text/html
S: Content-length: 183
S: Last modified: Wed, 09 Jul 1997 20:00:01 GMT
S:
S: <HTML> <HEAD>
S: <TITLE> MarshallSoft Computing, Inc. </TITLE>
S: </HEAD>
S: <H1> Hello </H1>
S: Hello, world!
S: </BODY> </HTML>
C: (Disconnects)
It is up to the HTTP client to interpret the HTML lines, for which
knowledege of the HTML specification is necessary.
Note that the client disconnects after receiving each page.
WIL4C Users Manual Page 32
5.0 Problems
Before attempting to run any of the example programs, you should
already be able to connect to the Internet and run your email client
program, such as Eudora or Pegasus Mail. You should also be
comfortable as a user of the Internet before attempting to program
Internet applications.
If you cannot get your application to run properly, first compile and
run the example programs. If you call us to report a possible bug in
the library, the first thing we will ask is if the example programs
run correctly.
If you are having trouble with a particular protocol, download the
RFCs from the Internic for detailed protocol information. Also
experiment with the appropriate example program. Unfortunately, there
is no substitute for trail and error! Another good resource are the
many books and magazines articles around dealing with the various
Internet protocols.
Although we will be happy to talk to you, we are not experts on the
Internet protocols. Our support is limited to the use of our library,
not the operation of the Internet protocols.
If your application does not run but the example applications run
correctly, then you have most likely made a programming mistake in
your application. MarshallSoft Computing cannot debug your
application, especially over the telephone!
We recommend the following steps if you believe that you have
discovered a bug in the library: (1) Create the smallest, simplest
test program possible that demonstrates the problem. (2) Document
your exact machine configuration and what error the test program
demonstrates. (3) Email your program to us at bugs@marshallsoft.com.
If the problem can be solved with an easy work-around, we will
publish the work-around. If the problem requires a modification to
the library, we will make the change and make the modified library
available to our customers without charge.
WIL4C Users Manual Page 33
6.0 Example Programs
There are 12 example programs, covering DNS, Finger, SMTP, POP3,
NNTP, FTP, and HTTP.
6.1 HOST
The HOST program uses the Domain Name System (DNS) to get internet
addresses for hosts for which their name is known. HOST can also get
port and server information, if available.
6.2 SFINGR, AFINGR, and FINGER
The three finger programs demonstrate the 3 methods of using the
WIL4C library. The FINGER protocol is presented in the section on
protocols.
SFINGR make only synchronous function calls. Refer to the section on
"Synchronous WIL" for information on synchronous calls.
AFINGR make asynchronous function calls. Refer to the section on
"Asynchronous WIL" for information on aynchronous calls.
FINGER make asynchronous function calls using the ASYNC commands.
Refer to "Using ASYNC Functions" for more information.
The Finger client program contact your Finger Server and requests
information for a particular user. Many hosts do not have finger
servers.
You can finger MarshallSoft Computing by specifying (at the prompt)
"msc@advicom.com".
6.3 FROM
The FROM client program logs onto your POP3 account and checks if
you having any waiting mail. If you do, it list the messages by
number along with the "From:" and "Subject:" fields, if any.
In order to use FROM, you must edit the file FROM.INI which contains
POP3 server addresses, and login name & password.
For example, suppose your ISP (Internet Service Provider) has host
address SUPERSERVE.COM, and your login name is billy. Then FROM.INI
may contain:
+---------------------------+
| POP3=mail.superserve.com |
| USER=billy |
| PASS=my_password |
+---------------------------+
WIL4C Users Manual Page 34
6.4 MAIL
The mail client program is similiar to FROM, except that it can also
send, receive, and delete mail.
In order to use MAIL, you must edit the file MAIL.INI which contains
SMTP & POP3 server addresses, and login name & password.
+---------------------------+
| SMTP=mail.superserve.com |
| POP3=mail.superserve.com |
| USER=billy |
| FROM=billy@superserve.com |
| PASS=my_password |
+---------------------------+
MAIL.INI is similiar to FROM.INI with the addition of the SMTP server
(for sending mail) and your email address (FROM line). In fact, you
can also use MAIL.INI for FROM.INI.
See section 6.9 (BCAST) for a description of the file format for
outgoing email messages. Note that the first line must be the
destination email address.
6.5 FTP
The FTP (File Transfer Protocol) client program communicats with a
FTP server, allowing for the transfer of ASCII and binary files.
Refer to the section on protocols for information on the FTP
protocol.
You must provide the login name and password in FTP.INI. For example,
if your email address is billy@superserve.com, FTP.INI would contain
the following for anonymous FTP.
+---------------------------+
| USER=anonymous |
| PASS=billy@superserve.com |
+---------------------------+
The FTP client program is capable of the following operations:
Command Description
CWD Changes the working directory at the host.
LIST List the contents of the current working directory.
ASCII Set ASCII transfer mode.
BINARY Sets binary transfer mode.
GET Receives specified file from the host.
PUT Sends specified file to the host.
QUIT Quits the FTP session.
Don't forget to set BINARY mode before downloading or uploading a
binary file.
WIL4C Users Manual Page 35
6.6 NEWS
The NEWS client program communicates with a NNTP (Network News
Transport Protocol) and provides the following functions:
Command Description
Group/
List List all groups.
Select Select a group for subsequent processing.
Header/
GetByNumber Selects header by number.
GetCurrent Selects current header.
Next Selects next header.
Last Select last header.
Article/
GetByNumber Selects article by number.
GetCurrent Selects current article.
Next Selects next article.
Last Select last article.
Quit Quits the NEWS server.
If the user specifies "Group/List", the incoming list of groups is
saved in the file NEWS.LST. If the user requests an article by number
"Article/GetByNumber", then the article is saved with file extension
".ART".
Refer to the section "NNTP Protocol" for information on NNTP.
6.7 VIEW
VIEW is HTTP client program which requests and displays source code
for a specified HTTP web page. VIEW is not a browser!
VIEW can be used as the basis for several types of HTTP clients. Some
ideas are as follows:
(1) VIEW can be used as the starting point for a web browser. Most of
the effort will be in writing the code necessary to interpret the
HTML (Hypertext Markup Language) text.
(2) VIEW could also be used as the basis for a "ROBOT" program, that
searches for email addresses. This is what some search engines do in
order to catalog the web sites on the Internet.
(3) VIEW could also be used as the starting point for a program that
connects to a search engine, copying search results for subsequent
anyalyis.
VIEW uses the synchronous style of programming.
WIL4C Users Manual Page 36
6.8 WHO_C and WHO_S
WHO_S is a server program which provides "WHOIS" service for three
individuals as requested by the client WHOIS program WHO_C.
After starting the server WHO_S, note the IP address. Next, start the
client WHO_C, using the WHO_S server IP address to specify the server.
Then, specify one of the three people in the WHOIS database: Mike,
Pam, or Lauren.
The purpose of the WHOIS programs is to demonstate how to write a
simple Internet server and matching client.
6.9 BCAST
BCAST is a SMTP client that emails a file to each address specified
in a list, such as emailing our newsletter to our customers.
Several pieces of information must be in the BCAST.INI file:
+-------------------------------+
| SMTP=your_SMTP_server_address |
| FROM=your_email_address |
| RCPT=file_of_email_addresses |
| MAIL=file_to_email |
+-------------------------------+
Outgoing email messages should be ASCII text files formatted as:
Line 1: Email address of destination (MAIL program only).
Line 2: "To: " header line.
Line 3: "From: " header line.
Line 4: "Subject: " header line.
Line 5: Blank line.
Line 6 to last_line: ASCII email message.
Example outgoing email message:
+-----------------------------------------------------+
|mike@marshallsoft.com |
|To: mike@marshallsoft |
|From: pam@traveller.com |
|Subject: Test message |
| |
|The mail destination address must be the 1st line for|
|email being sent with the MAIL example program. The |
|"To:", "From:", and "Subject:" fields are optional. |
|There should be a blank line before the body of the |
|message. [7/25/97]. |
+-----------------------------------------------------+
WIL4C Users Manual Page 37
7.0 Legal Issues
7.1 Registration
WIL4C may be registered for $95 plus $6 S&H ($12 outside of North
America).
To order, contact us as shown on the title page of this manual. All
prices are guaranteed for one year from the release date.
Multiple copy discounts (3 or more) and site licenses are available.
Please call for details.
We accept American Express, VISA, MasterCard, Discover, checks in US
dollars drawn on a US bank, International Postal Money Orders,
purchase orders (POs) from recognized US schools and companies listed
in Dun & Bradstreet, and COD (street address and phone number
required) within the USA (plus a $5 COD charge).
For credit card orders, be sure to include the account number, the
expiration date, the exact name on the card, and the complete card
billing address (the address to which the credit card bill is
mailed).
Print the file INVOICE.TXT if a "Pro Forma" invoice is needed.
If you wish to update from an older version of WIL4C, send $25 plus
$6 S&H ($12 S&H outside of North America).
The registered package includes:
o Win16 & Win32 WIL4C Libraries w/o shareware screens.
o Win16 & Win32 source code for WIL and ASYNC.
o Printed Users Manual & Reference Manual.
o Telephone and email support for one year.
The registered user will receive the latest version of WIL4C shipped
by US second day priority mail (packet airmail overseas). A 3.5"
HD diskette is provided.
WIL4C Users Manual Page 38
7.2 License
MarshallSoft Computing, Inc. grants the registered user of WIL4C the
right to use one copy of the WIL4C library (in object form) on a
single computer in the development of any software product (other
more than one computer at the same time. The source code for the
library (WIL.C and ASYNC.C) is copyrighted by MarshallSoft Computing
and may not be released in whole or in part. Products developed using
WIL4C may be distributed without royalty.
7.3 Warranty
MARSHALLSOFT COMPUTING, INC. DISCLAIMS ALL WARRANTIES RELATING TO
THIS SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT
LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND
SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING, INC. NOR
ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION, OR
DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT,
CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR
INABILITY TO USE SUCH SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC.
HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO
EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH
DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO USE THE
SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON USING THE
SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND PERFORMANCE OF THE
SOFTWARE.
Some states do not allow the exclusion of the limit of liability for
consequential or incidental damages, so the above limitation may not
apply to you.
This agreement shall be governed by the laws of the State of Alabama
and shall inure to the benefit of MarshallSoft Computing, Inc. and
any successors, administrators, heirs and assigns. Any action or
proceeding brought by either party against the other arising out of
or related to this agreement shall be brought only in a STATE or
FEDERAL COURT of competent jurisdiction located in Madison County,
Alabama. The parties hereby consent to in personam jurisdiction of
said courts.
WIL4C Users Manual Page 39
8.0 Summary
8.1 Revision History
Version 1.0: 28 July, 1997.
o The initial release of WIL4C.
[reserved]
8.2 WIL4C Function Summary
Refer to the WIL4C Reference Manual (WIL4C_R.TXT) for detailed
information on the communications and support functions. A one line
summary of each function follows on the next page.
There are 54 functions in the WIL library.
Also examine the usage of these functions in the example programs.
WIL4C Users Manual Page 40
+-------------------------------------------------------------------+
| wilAccept : Accepts incoming connection. |
| wilAttach : Attaches (initializes) winsock. |
| wilAskHostByAddr : Request host information from server. |
| wilAskHostByName : Request host information from server. |
| wilAskProtoByName : Request protocol information. |
| wilAskProtoByNumber : Request protocol information. |
| wilAskServByName : Request server information. |
| wilAskServByPort : Request server information. |
| wilAwaitEvent : Set asynchronous event winsock mask. |
| wilBind : Bind socket to specified address & port nunber. |
| wilCancelBlocking : Cancels blocking call. |
| wilCloseSocket : Close socket. |
| wilConnect : Initiate connection to remote port. |
| wilDataIsReady : Is socket readable (data is ready). |
| wilDebug : Returns bebug value. |
| wilErrorText : Get text associated with error code. |
| wilGetDescription : Get winsock description text. |
| wilGetHostAddr : Get host address. |
| wilGetHostAlias : Get host name alias. |
| wilGetHostDotted : Get host dotted address. |
| wilGetHostName : Get host name. |
| wilGetMaxSockets : Get maximum number of sockets supported. |
| wilGetMaxUDPSize : Get maximum UDP packet size. |
| wilGetMyHostAddr : Get local host address. |
| wilGetMyHostDotted : Get local host (dotted) address. |
| wilGetMyHostName : Get local host name. |
| wilGetProtoName : Get protocol name. |
| wilGetProtoNumber : Get protocol number. |
| wilGetServName : Get server name. |
| wilGetServPort : Get server port. |
| wilGetSystemInfo : Get winsock system information. |
| wilGetVendorInfo : Get winsock vendor information. |
| wilIsBlocking : Is winsock currently blocking ? |
| wilIsConnected : Is socket connected to remote ? |
| wilIsDotted : Is dotted string properly formed ? |
| wilListen : Listen for incoming connection attempts. |
| wilLocalSockAddr : Get local sock address for connected socket. |
| wilLocalSockPort : Get local sock port number for connected sock. |
| wilParseDecimal : Parse decimal response code. |
| wilPeekSocket : Peek into socket. |
| wilReadLine : Read line terminated with linefeed. |
| wilReadOOB : Read Out-Of-Bound data. |
| wilReadSocket : Read from socket. |
| wilReadString : Read string from socket. |
| wilRelease : Release (free) winsock. |
| wilRemoteSockAddr : Get remote sock address for connected socket. |
| wilRemoteSockPort : Get remote port number for connected socket. |
| wilSetOOB : Sets Out-Of_Bound data state. |
| wilSocketStatus : Get socket read/write status. |
| wilTcpSocket : Create TCP socket. |
| wilWriteOOB : Write Out-Of_Bounds data to socket. |
| wilWriteSocket : Write buffer to socket. |
| wilWriteString : Write string to socket. |
| wilWriteLine : Write linefeed terminated line to socket. |
+-------------------------------------------------------------------+
WIL4C Users Manual Page 41
9.0 Other MarshallSoft Computing Products
Several shareware products are available from MarshallSoft Computing.
9.1 The Windows Standard Communications Library for C/C++
The Windows Standard Communications Library for C/C++ (WSC4C) is a
Windows based asynchronous serial communications library designed for
software developers programming in C/C++. WSC4C uses the Windows
communications driver. Both 16-bit amd 32-bit DLLs are included along
with 5 example programs.
The Windows Standard Communications Library for C/C++ (WSC4C) is
available for $75 plus $6 S&H ($12 S&H overseas).
9.2 The Personal Communications Library for Windows (C/C++)
The Personal Communications Library for Windows (PCL4W) is a Windows
based [Win16] asynchronous communications library designed for
software developers programming in C/C++. Unlike WSC4C, PCL4W
interfaces to the serial port hardware directly. PCL4W also supports
multiport boards such as those made by DigiBoard and BOCA.
The Personal Communications Library for Windows (PCL4W) is available
for $75 plus $6 S&H ($12 S&H overseas).
9.3 The Personal Communications Library for C/C++ / DOS
PCL4C is similar to PCL4W except that it is designed for DOS.
Includes support for both 16-bit and 32-bit protected mode.
9.4 Libraries for Other Languages
We have communications libraries for C/C++, Turbo Pascal, Visual
Basic, and PowerBASIC. Check our BBS or WEB site.
PCL4C : C/C++, DOS [include 16-bit & 32-bit protected mode].
PCL4P : Turbo Pascal, DOS [includes 16-bit protected mode].
PCL4VB : Visual Basic, DOS.
PCL4PB : Power Basic, DOS.
PCL4W : C/C++, Windows 3.1 & Win 95, talks to hardware directly.
PCLVBW : Visual Basic, Win 3.1 & Win 95, talks to hardware directly.
WSC4C : C/C++, Win 3.1, Win 95, Win NT. Uses Windows API.
WSC4VB : Visual Basic, Win 3.1, Win 95, Win NT. Uses Windows API.
WSC4D : Borland DELPHI, Win 3.1, Win 95, Win NT. Uses Windows API.
WIL4C Users Manual Page 42
